Hi @rosenhouse. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Thanks!

/ok-to-test
/approve

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: robscott, rosenhouse

The full list of commands accepted by this bot can be found here.

The pull request process is described here

This is documented just below, do you think that summarizing here is needed too?

https://github.com/kubernetes-sigs/service-apis/blob/9c92ae4817fcf62a80285a246fd4913774600bd6/apis/v1alpha1/gateway_types.go#L536-L552

@jpeach The code comments you quoted do not appear in the docs page (try doing an in-page text search for is an address selected by name at this url.

Also: I was trying to understand what an example of a NamedAddress might look like (slack thread). As someone new to the project, having an extra note giving the example of "static" or "elastic" IP helped me better understand how this field is meant to be used.

@jpeach The code comments you quoted do not appear in the docs page

ahmetb/gen-crd-api-reference-docs#21

:(

This is a general problem with the online docs. We have a lot of API-relevant information attached to constants in the Go code which isn't exposed in the HTML docs. It doesn't seem practical to hoist all that up to the corresponding types, and in some cases the types aren't anchored all the way up to a CRD spec (e.g. we don't constrain condition types using the type system).

@jpeach Should we restructure how we document our code to so the reference docs are more useful? We could either duplicate documentation or move the majority of the description/types to where they are actually used.

@rosenhouse @jpeach Although I don't love duplicating documentation, I think it's worth it for the sake of understandable reference docs.

@rosenhouse A friendly ping to get this PR moving forward.

@hbagdi I think I've got it cleaned up, please take a look again.

/lgtm